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Programming language considerations 

MQSeries provides support for the following programming languages: 

• C 

- C++ (MQSeries for ADC, AS/400, HP-UX, OS/2. OS/390, Sun Solaris, Compaq Tru64 UNIX, 
and Windows NT only). See the MQSeries Usirtf C++ book for information about coding 
MQSeries programs in C++. 

• Visual Basic (MQSeries for Windows and Windows NT only). See the MQSeries for Windows 
Version 2.0 User's Guide and the MQSeries for Windows Version 2. 1 User's Guide for 
information about coding MQSeries programs in Visual Basic. 

. COBOL. 

• Assembler language (MQSeries for OS/390 only). 
. RPG (MQSeries for AS/400 only). 

. PL/I (MQSeries for OS/390, ADC, OS/2 Warp, VSE/ESA, and Windows NT only). 

• TAL (MQSeries for Tandem Nan Stop Kernel only). 

The call interface; and how you can code the calls in each of these languages, is described in the 
M QSeries Application Programming Reference manual. 

MQSeries provides data definition files to assist you with the writing of your applications. For a full 
description, see A ppendix F. MQSeries data definition files . 

If you can choose which language to code your programs in, you should consider the maximum length 
of the messages that your programs will process. If your programs will process only messages of a 
known maximum length, you can code them in any of the supported programming languages. But if you 
do not know the maximum length of the messages the programs will have to process, the language you 
choose will depend on whether you are writing a CICS, IMS, or batch application: 

IMS and batch 

Code the programs in C, PL/1, or assembler language to use the facilities these languages offer for 
obtaining and releasing arbitrary amounts of memory. Alternatively, you could code your 
programs in COBOL, but use assembler language, PL/1, or C subroutines to get and release 
storage. 

CICS 

Code the programs in any language supported by CICS. The EXEC CICS interface provides the 
calls for managing memory, if necessary. 

Coding in C 

See A ppendix A, Lang uage compilers and assemblers for the compilers that you can use to process your 
C programs. 

Note the information in the following sections when coding MQSeries programs in C. 
Parameters of tbe MQI calls 



Parameters that are input-only and of type MQHCONN. MQHOBJ, or MQLONG are passed by value; 
for all other parameters, the address of the parameter is passed by value. 

Not all parameters that are passed by address need to be specified every time a function is invoked. 
Where a particular parameter is not required, a null pointer can be specified as the parameter on the 
function invocation, in place of the address of the parameter data. Parameters for which this is possible 
are identified in the call descriptions. 

No parameter is returned as the value of the function; in C terminology, this means that all functions 
return void. 

The attributes of the function are defined by the MQENTRY macro variable; the value of this macro 
variable depends on the environment. 

Parameter! with undefined data type 

The MQGET, MQPUT, and MQPUT1 functions each have one parameter that has an undefined data 
type, namely the Buffer parameter. This parameter is used to send and receive the application's 
message data. 

Parameters of this sort are shown in the C examples as arrays of MQBVTE. It is valid to declare the 
parameters in this way, but it is usually more convenient to declare them as the particular structure that 
describes the layout of the data in the message. The function parameter is declared as a pointer-to-void, 
and so the address of any sort of data can be specified as the parameter on the function invocation. 

Data types 

All data types are defined by means of the typedef statement. For each data type, the corresponding 
pointer data type is also defined. The name of the pointer data type is the name of the elementary or 
structure data type prefixed with the letter "P" to denote a pointer. The attributes of the pointer are 
defined by the MQPOINTER macro variable; the value of this macro variable depends on the 
environment. The following illustrates how pointer data types are declared: 

•define MQPOINTER /* depends on environment */ 

typedef HQ LONG MQPOINTER PMQLONG; /* pointer to HQ LONG */ 
typedef HQKD MQPOINTER PKQMD; /* pointer to MQKD */ 

Manipulating binary strings 

Strings of binary data are declared as one of the MQBYTEn data types. Whenever you copy, compare, 
Or set fields of this type, use the C functions memcpy, raemcrap, or mern set: 

•include <string.h> 
•include "cmqc.h" 

MQMD MyMsgDesc; 

meiacpy( MyMsgDesc. Msg Id, /* set "Msgld" field to nulls */ 

MQ_HI_NONE, /* ...using named constant */ 

sizeof (MyMsgDesc. Msgld) ) ; 
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memset (MyMsgDesc. Correl Id, /* set "Correlld" field to nulls */ 

0x00, /* ...using a different method */ 

sizeof (MQBYTE2 4) ) ; 

Do not use the string functions strcpy, strcmp, stmcpy, or stmcmp because these do not work correcdy 
with data declared as MQBYTE24. 

Manipulating character strings 

When the queue manager returns character data to the application, the queue manager always pads the 
character data with blanks to the defined length of the field. The queue manager does not return null- 
terminated strings, but you can use them in your input. Therefore, when copying, comparing, or 
concatenating such strings, use the string functions stmcpy, stmcmp, or stmcat. 

Do not use the string functions that require the string to be terminated by a null (strcpy, strcmp, and 
strcat). Also, do not use the function strien to determine the length of the suing; use instead the sizeof 
function to determine the length of the field. 

Initial values for structures 

The include file <cmqc.h> defines various macro variables that may be used to provide initial values for 
the structures when instances of those structures are declared. These macro variables have names of the 
form MQxxxDEFAULT, where MQxxx represents the name of the structure. Use them like this: 

MQMD MyMsgDesc ■ ( MQMD_DE FAULT ) ; 
KQPMO MyPutOpts « ( MQPKO_DE FAULT ) ; 

For some character fields, the MQI defines particular values that are valid (for example, for the 
strucid fields or for the Format field in MQMD). For each of the valid values, two macro variables are 
provided: 

• One macro variable defines the value as a string whose length, excluding the implied null, 
matches exactly the defined length of the field. For example, (the symbol represents a blank 
character): 

•define MQMD_STRUC_I D "MD * 
•define MQFMT_STRING "MQSTR 

Use this form with the memcpy and memcmp functions. 

• The other macro variable defines the value as an array of char, the name of this macro variable is 
the name of the string form suffixed with "ARRAY". For example: 

•define MQKD_STRUC_I D_ARRAY 'M' , ' D' , * ■ 

•define MQFHT_STRING_ARRAY 'M' , 'Q ' , ' S ' , ' T* , 'R 1 , • \' • 

Use this form to initialize the field when an instance of the structure is declared with values 
different from those provided by the MQMDDEFAULT macro variable. 

Initial values for dynamic structures 
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When a variable number of instances of a structure are required, the instances are usually created in 
main storage obtained dynamically using the calloc or malloc functions. 

To initialize the fields in such structures, the following technique is recommended: 

1 . Declare an instance of the structure using the appropriate MQxxx DEFAULT macro variable to 
initialize the structure. This instance becomes the "model" for other instances: 

MQMD ModelMsgDesc - { MQMD_DE FAULT } ; 

/* declare model instance */ 

The static or auto keywords can be coded on the declaration in order to give the model instance 
static or dynamic lifetime, as required. 

2. Use the calloc or malloc functions to obtain storage for a dynamic instance of the structure: 
PMQMD InstancePtr; 

InstancePtr = malloc (sizeof (MQMD) ) ; 

/* get storage for dynamic instance */ 

3. Use the memcpy function to copy the model instance to the dynamic instance: 

memcpy (InstancePtr, 4ModelMsgDesc, sizeof (MQMD) ) ; 

/* initialize dynamic instance */ 

Use from C++ 

For the C++ programming language, the header files contain the following additional statements that 
are included only when a C++ compiler is used: 

• ifdef t cplusplus 

extern "C" ( 
•endif 

/• rest of header file */ 

•ifdef cplusplus 

) 

•endif 

Coding in COBOL 

See Ap pendix A. Language compilers and assemblers for the compilers that you can use to process your 
COBOL programs. 

Note the information in the following sections when coding MQSeries programs in COBOL. 
Named constants 

In this book, the names of constants are shown containing the underscore character (_) as part of the 
name. In COBOL, you must use the hyphen character (-) in place of the underscore. 
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Constants that have character-string values use the single quotation mark character (*) as the string 
delimiter. To make the compiler accept this character, use the compiler option APOST. 

The copy file CMQV contains declarations of the named constants as level- 10 items. To use the 
constants, declare the level -01 item explicitly, then use the COPY statement to copy in the declarations 
of the constants: 

WORKING-STORAGE SECTION. 
01 KQM- CONSTANTS . 
COPY CMQV- 

However, this method causes the constants to occupy storage in the program even if they are not 
referred to. If the constants are included in many separate programs within the same run unit, multiple 
copies of the constants will exist-this may result in a significant amount of main storage being used. 
You can avoid this situation by adding the GLOBAL clause to the levd-01 declaration: 

* Declare * global structure to hold the constants 
01 MOM-CONSTANTS GLOBAL. 
COPY CMQV. 

This causes storage to be allocated for only one set of constants within the run unit; the constants, 
however, can be referred to by any program within the run unit, not just the program that contains the 
levd-01 declaration. 

Coding in System/390^ assembler language 

System/390 assembler is supported on OS/390 only. 

See A ppendix A, Lang ua g e c ompilers and assemblers for the assemblers that you can use to process 
your assembler -language programs. 

Note the information in the following sections when coding MQSeries for OS/390 programs in 
assembler language. 

Names 

In this book, the names of parameters in the descriptions of calls, and the names of fidds in the 
descriptions of structures are shown in mixed case. In the assembler-language macros supplied with 
MQSeries, all names are in uppercase. 

Using the MQ1 calls 

The MQI is a call interface, so assembler-language programs must observe the OS linkage convention. 
In particular, before they issue an MQI call, assembler-language programs must point register R13 at a 
save area of at least 18 full words. This save area is to provide storage for the called program. It stores 
the registers of the caller before their contents are destroyed, and restores the contents of the caller's 
registers on return. 

Note: This is of particular importance for CICS assembler-language programs that use the DFHEIENT 
macro to set up their dynamic storage, but that choose to override the default DATAREG from 
R13 to other registers. When the CICS Resource Manager Interface receives control from the 



stub, it saves the current contents of the registers at the address to which R13 is pointing. Failing 
to reserve a proper save area for this purpose gives unpredictable results, and will probably 
cause an abend in CICS. 

Declaring constants 

Most constants are declared as equates in macro CMQA. However, the following constants cannot be 
defined as equates, and these are not included when you call the macro using default options: 

MQACT NONE 

MQCI_NONE 

MQFMTNONE 

MQFMTADMIN 

MQFMT_COMMAND_ 1 

MQFMTCOMMAND2 

MQFMT DEAD LETTERHEADER 

MQFMT_EVENT 

MQFMT IMS 

MQFMT~IMS_VAR_STRING 

MQFMTPCF 

MQFMTSTRJNG 

MQFMTTRJGGER 

MQFMT_XM3T_Q_HEADER 

MQMI_NONE 

To include them, add the keyword EQUONLY=NO when you call the macro. 

CMQA is protected against multiple declaration, so you can include it many times. However, the 
keyword EQUONLY takes effect only the first time the macro is induded. 

Specifying the name of a structure 

To allow more than one instance of a structure to be declared, the macro that generates the structure 
prefixes the name of each fidd with a user-specifiable string and an underscore character (_). Specify 
the string when you invoke the macro. If you do not specify a string, the macro uses the name of the 
structure to construct the prefix: 

* Declare two object descriptors 

CMQODA Prefix used»-MQOD_" (the default) 

MY_MQOD CMQODA Prefix used="MY_MQOD_" 

The structure declarations in the MQSeries Application P ro gramming Reference manual show the 
default prefix. 

Specifying the form of a structure 

The macros can generate structure declarations in one of two forms, controlled by the DSECT 
parameter: 
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DSECT=YES An assembler-language DSECT instruction is used to start a new data section; the 
structure definition immediately follows the DSECT statement. No storage is 
allocated, so no initialization is possible. The label on the macro invocation is 
used as the name of the data section; if no labd is specified, the name of the 
structure is used. 

DSECT=NO Assembler-language DC instructions are used to define the structure at the current 

position in the routine. The fidds are initialized with values, which you can 
specify by coding the relevant parameters on the macro invocation. Fields for 
which no values are specified on the macro invocation are initialized with default 
values. 

DSECT=NO is assumed if the DSECT parameter is not specified. 
Controlling the listing 

You can control the appearance of the structure dedaration in the assembler-language listing by means 
of the LIST parameter 

LIST=YES The structure declaration appears in the assembler-language listing. 

LIST=NO The structure declaration does not appear in the assembler-language listing. This 

is assumed if the LIST parameter is not specified. 

Specifying initial values for fidds 

You can specify the value to be used to initialize a field in a structure by coding the name of that fidd 
(without the prefix) as a parameter on the macro invocation, accompanied by the value required. 

For example, to dedare a message descriptor structure with the Msg Type field initialized with 
MQMT REQUEST, and the RepiyToo fidd initialized with the string MY_REPLY_TO_QUEUE, you 
could use the following code: 

MY_MQHD CMQMDA MSGTYPE-MQHT_REQUEST, X 

RE PLYTOQ«MY_RE PLY_TO_QUEUE 

If you sperify a named constant (or equate) as a value on the macro invocation, you must use the 
CMQA macro to define the named constant You must not endose in single quotation marks C ') values 
that are character strings. 

Writing reenterable programs 

MQSeries uses its structures for both input and output. If you want your program to remain reenterable, 
you should: 

1 . Define working storage versions of the structures as DSECTs, or define the structures inline 
within an already-defined DSECT. Then copy the DSECT to storage that is obtained using: 
o For batch and TSO programs, the STORAGE or GETMAIN OS/390 assembler macros 
o For CICS, the working storage DSECT (DFHEISTG) or the EXEC CICS GETMAIN 
command 
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To correctly initialize these working storage structures, copy a constant version of the 
corresponding structure to the working storage version. 

Note: The MQMD and MQXQH structures are each more than 256 bytes long. To copy these 
structures to storage, you will have to use the MVCL assembler instruction. 

2. Reserve space in storage by using the LIST form (mf-l) of the CALL macro. When you use the 
CALL macro to make an MQI call, use the EXECUTE form (mf-e) of the macro, using the 
storage reserved earlier, as shown in the example under "Using CEDF" . For more examples of 
how to do this, see the assembler language sample programs as shipped with MQSeries. 

Use the assembler language RENT option to help you determine if your program is reenterable. 

For information on writing reenterable programs, see the MVS/ESA Application Development Guide: 
Assembler Language Programs^ GC28-1644. 

Using CEDF 

If you want to use the CICS-supplied transaction, CEDF (CICS Execution Diagnostic Farility) to help 
you to debug your program, you must add the , vl keyword to each call statement, for example: 

CALL MQCONff , ( NAME , HCONK , COMPCODE , REASON ) , MF- ( E , PARMAREA) , VL 

The above example is reenterable assembler-language code where parmarea is an area in the working 
storage you spedfied. 

Coding in RPG 

RPG is supported on OS/400 only. 

See Appe nd ix A, Lang ua ge com piler s. and assemblers for the compilers that you can use to process your 
RPG programs. 

In this book, the parameters of calls, the names of data types, the fields of structures, and the names of 
constants are described using thrir long names. In RPG, these names are abbreviated to six or fewer 
uppercase characters. For example, the field Msg Type becomes mdmt in RPG. For more information, see 
the MQSeries for AS/400 Application Programming Reference (ILE RPG) manual . 

Coding in PL/I 

PUI is supported on AJX, OS/390, OS/2 Warp. VS&ESA. and Windows NT only. 

See Appendix A. Language compilers and assemblers for the compilers that you can use to process your 
PL/I programs. 

Note the information in the following sections when coding MQSeries for OS/390 programs in PL/I. 
Structures 

Structures are dedared with the BASED attribute, and so do not occupy any storage unless the program 
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declares one or more instances of a structure. 
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An instance of a structure can be declared by using the like attribute, for example: 

del my_aqmd like HQHD; /* one Instance */ 

del ray~other_iaepsd like MQKD; /* another one •/ 

The structure fields are declared with the INITIAL attribute; when the like attribute is used to declare 
an instance of a structure, that instance inherits the initial values defined for that structure. Thus it is 
necessary to set only those fields where the value required is different from the initial value. 

PL/I is not sensitive to case, and so the names of calls, structure fields, and constants can be coded in 
lowercase, uppercase, or mixed case. 

Named constants 

The named constants are declared as macro variables; as a result, named constants which are not 
referenced by the program do not occupy any storage in the compiled procedure. However, the compiler 
option which causes the source to be processed by the macro preprocessor must be specified when the 
program is compiled. 

All of the macro variables are character variables, even the ones which represent numeric values. 
Although this may seem counter intuitive, it does not result in any data-type conflict after the macro 
variables have been substituted by the macro processor, for example: 

Idcl MQKD_STRUC_IO char; 
IMQMD_STRUC_ID - ' * 'KD '"; 

Idcl MQHD_VERSION_l char; 
IMQMD_VERSI0N_1 - 

Coding in TAL 

TAL is supported on Tandem NonStop Kernel only. 

See A ppendix A. Languagc . compilers and assemblers for the compilers that you can use to process your 
TAL programs. 

Note the following when coding MQSeries for Tandem NonStop Kernel programs in TAL: 

• The MQI library (bound into the application process) does not open $ RECEIVE and does not 
open STMP (TM/MP transaction pseudo-file) itself, so you may code your application to use 
these features. 

• The MQI library uses a SERVERCLASS_SEND_0 call in initial communication with the Queue 
Manager. While connected, it maintains two process file opens (with the LINKMON process and 
a Local Queue Manager Agent) and a small number of disk file opens (fewer than 10). 
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